Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# Handle and Descriptor Functions

This section describes the OCI handle and descriptor functions.

Table 15-3 Handle and Descriptor Functions

Function | Purpose
--- | ---
OCIAttrGet() | Get the attributes of a handle
OCIAttrSet() | Set an attribute of a handle or descriptor
OCIDescriptorAlloc() | Allocate and initialize a descriptor or LOB locator
OCIDescriptorFree() | Free a previously allocated descriptor
OCIHandleAlloc() | Allocate and initialize a handle
OCIHandleFree() | Free a previously allocated handle
OCIParamGet() | Get a parameter descriptor
OCIParamSet() | Set parameter descriptor in COR handle

## OCIAttrGet()

Purpose

This call is used to get a particular attribute of a handle.

Syntax

    sword OCIAttrGet ( CONST dvoid    *trgthndlp,
                       ub4            trghndltyp,
                       dvoid          *attributep,
                       ub4            *sizep,
                       ub4            attrtype,
                       OCIError       *errhp );

Parameters

trgthndlp (IN)

  Pointer to a handle type. The actual handle can be a statement handle, a session handle, and so on. When this call is used to get encoding, users are allowed to check against either an environment or statement handle.

trghndltyp (IN)

  The handle type. Valid types are:

- `OCI_DTYPE_PARAM`, for a parameter descriptor

- `OCI_HTYPE_STMT`, for a statement handle

- Any handle type in Table 2-1, "OCI Handle Types".

attributep (OUT)

  Pointer to the storage for an attribute value. Will be in the encoding specified by the `charset` parameter of a previous call to `OCIEnvNlsCreate()`.

sizep (OUT)

  The size of the attribute value, always in bytes because `attributep` is a `dvoid` pointer. This can be passed as `NULL` for most attributes because the sizes of non-string attributes are already known by the OCI library. For `text*` parameters, a pointer to a `ub4` must be passed in to get the length of the string.

attrtype (IN)

  The type of attribute being retrieved. The types are listed in this document at:

  See Also: Appendix A, "Handle and Descriptor Attributes", for a list of handle types and their readable attributes

errhp (IN/OUT)

  An error handle you can pass to `OCIErrorGet()` for diagnostic information in the event of an error.

Comments

This call is used to get a particular attribute of a handle. `OCI_DTYPE_PARAM` is used to do implicit and explicit describes. The parameter descriptor is also used in direct path loading. For implicit describes, the parameter descriptor has the column description for each select list. For explicit describes, the parameter descriptor has the describe information for each schema object we are trying to describe. If the top-level parameter descriptor has an attribute which is itself a descriptor, use `OCI_ATTR_PARAM` as the attribute type in the subsequent call to `OCIAttrGet()`to get the Unicode information in an environment or statement handle.

See Also: "Examples Using OCIDescribeAny()" and "Describing Select-list Items"

A function closely related to `OCIAttrGet()` is `OCIDescribeAny()`, which is a generic describe call that describes existing schema objects: tables, views, synonyms, procedures, functions, packages, sequences, and types. As a result of this call, the describe handle is populated with the object-specific attributes which can be obtained through an `OCIAttrGet()` call.

Then an `OCIParamGet()` on the describe handle returns a parameter descriptor for a specified position. Parameter positions begin with 1. Calling `OCIAttrGet()` on the parameter descriptor returns the specific attributes of a stored procedure or function parameter or a table column descriptor as the case may be. These subsequent calls do not need an extra round trip to the server because the entire schema object description is cached on the client side by `OCIDescribeAny()`. Calling `OCIAttrGet()` on the describe handle can also return the total number of positions.

In UTF-16 mode, particularly when executing a loop, try to reuse the same pointer variable corresponding to an attribute and copy the contents to local variables after `OCIAttrGet()` is called. If multiple pointers are used for the same attribute, a memory leak can occur.

Related Functions

OCIAttrSet()

## OCIAttrSet()

Purpose

This call is used to set a particular attribute of a handle or a descriptor.

Syntax

    sword OCIAttrSet ( dvoid       *trgthndlp,
                       ub4         trghndltyp,
                       dvoid       *attributep,
                       ub4         size,
                       ub4         attrtype,
                       OCIError    *errhp );

Parameters

trgthndlp (IN/OUT)

  Pointer to a handle type whose attribute gets modified.

trghndltyp (IN/OUT)

  The handle type.

attributep (IN)

  Pointer to an attribute value. The attribute value is copied into the target handle. If the attribute value is a pointer, then only the pointer is copied, not the contents of the pointer. String attributes must be in the encoding specified by the `charset` parameter of a previous call to `OCIEnvNlsCreate()`.

size (IN)

  The size of an attribute value. This can be passed in as 0 for most attributes as the size is already known by the OCI library. For `text*` attributes, a `ub4` must be passed in set to the length of the string in bytes, regardless of encoding.

attrtype (IN)

  The type of attribute being set.

errhp (IN/OUT)

  An error handle you can pass to `OCIErrorGet()` for diagnostic information in the event of an error.

Comments

See Appendix A, "Handle and Descriptor Attributes", for a list of handle types and their writable attributes.

Related Functions

OCIAttrGet()

## OCIDescriptorAlloc()

Purpose

Allocates storage to hold descriptors or LOB locators.

Syntax

    sword OCIDescriptorAlloc ( CONST dvoid   *parenth,
                               dvoid         **descpp,
                               ub4           type,
                               size_t        xtramem_sz,
                               dvoid         **usrmempp);

Parameters

parenth (IN)

  An environment handle.

descpp (OUT)

  Returns a descriptor or LOB locator of desired type.

type (IN)

  Specifies the type of descriptor or LOB locator to be allocated:

- `OCI_DTYPE_SNAP` - specifies generation of snapshot descriptor of C type `OCISnapshot`

- `OCI_DTYPE_LOB` - specifies generation of a LOB value type locator (for a `BLOB` or `CLOB`) of C type `OCILobLocator`

- `OCI_DTYPE_FILE` - specifies generation of a FILE value type locator of C type `OCILobLocator`.

- `OCI_DTYPE_ROWID` - specifies generation of a `ROWID` descriptor of C type `OCIRowid`.

- `OCI_DTYPE_DATE` - specifies generation of an `ANSI` `DATE` descriptor of C type `OCIDateTime`

- `OCI_DTYPE_TIMESTAMP` - specifies generation of a `TIMESTAMP` descriptor of C type `OCIDateTime`

- `OCI_DTYPE_TIMESTAMP_TZ` - specifies generation of a `TIMESTAMP` `WITH` `TIME` `ZONE` descriptor of C type `OCIDateTime`

- `OCI_DTYPE_TIMESTAMP_LTZ` - specifies generation of a `TIMESTAMP` `WITH` `LOCAL` `TIME` `ZONE` descriptor of C type `OCIDateTime`

- `OCI_DTYPE_INTERVAL_YM` - specifies generation of an `INTERVAL` `YEAR` `TO` `MONTH` descriptor of C type `OCIInterval`

- `OCI_DTYPE_INTERVAL_DS` - specifies generation of an `INTERVAL` `DAY` `TO` `SECOND` descriptor of C type `OCIInterval`

- `OCI_DTYPE_COMPLEXOBJECTCOMP` - specifies generation of a complex object retrieval descriptor of C type `OCIComplexObjectComp`.

- `OCI_DTYPE_AQENQ_OPTIONS` - specifies generation of an Advanced Queuing enqueue options descriptor of C type `OCIAQEnqOptions`.

- `OCI_DTYPE_AQDEQ_OPTIONS` - specifies generation of an Advanced Queuing dequeue options descriptor of C type `OCIAQDeqOptions`.

- `OCI_DTYPE_AQMSG_PROPERTIES` - specifies generation of an Advanced Queuing message properties descriptor of C type `OCIAQMsgProperties`.

- `OCI_DTYPE_AQAGENT` - specifies generation of an Advanced Queuing agent descriptor of C type `OCIAQAgent`.

xtramem_sz (IN)

  Specifies an amount of user memory to be allocated for use by the application for the lifetime of the descriptor.

usrmempp (OUT)

  Returns a pointer to the user memory of size `xtramem_sz` allocated by the call for the user for the lifetime of the descriptor.

Comments

Returns a pointer to an allocated and initialized descriptor, corresponding to the type specified in `type`. A non-`NULL` descriptor or LOB locator is returned on success. No diagnostics are available on error.

This call returns `OCI_SUCCESS` if successful, or `OCI_INVALID_HANDLE` if an out-of-memory error occurs.

See Also: For more information about the `xtramem_sz` parameter and user memory allocation, refer to "User Memory Allocation"

Related Functions

OCIDescriptorFree()

## OCIDescriptorFree()

Purpose

Deallocates a previously allocated descriptor.

Syntax

    sword OCIDescriptorFree ( dvoid    *descp,
                              ub4      type );

Parameters

descp (IN)

  An allocated descriptor.

type (IN)

  Specifies the type of storage to be freed. The specific types are:

- `OCI_DTYPE_SNAP` - snapshot descriptor

- `OCI_DTYPE_LOB` - a LOB value type descriptor

- `OCI_DTYPE_FILE` - a FILE value type descriptor

- `OCI_DTYPE_ROWID` - a `ROWID` descriptor

- `OCI_DTYPE_DATE` - an `ANSI` `DATE` descriptor

- `OCI_DTYPE_PARAM` - a parameter descriptor

- `OCI_DTYPE_TIMESTAMP` - a `TIMESTAMP` descriptor

- `OCI_DTYPE_TIMESTAMP_TZ` - a `TIMESTAMP` `WITH` `TIME` `ZONE` descriptor

- `OCI_DTYPE_TIMESTAMP_LTZ` - a `TIMESTAMP` `WITH` `LOCAL` `TIME` `ZONE` descriptor

- `OCI_DTYPE_INTERVAL_YM` - an `INTERVAL` `YEAR` `TO` `MONTH` descriptor

- `OCI_DTYPE_INTERVAL_DS` - an `INTERVAL` `DAY` `TO` `SECOND` descriptor

- `OCI_DTYPE_COMPLEXOBJECTCOMP` - a complex object retrieval descriptor

- `OCI_DTYPE_AQENQ_OPTIONS` - an AQ enqueue options descriptor

- `OCI_DTYPE_AQDEQ_OPTIONS` - an AQ dequeue options descriptor

- `OCI_DTYPE_AQMSG_PROPERTIES` - an AQ message properties descriptor

- `OCI_DTYPE_AQAGENT` - an AQ agent descriptor

Comments

This call frees storage associated with a descriptor. Returns `OCI_SUCCESS` or `OCI_INVALID_HANDLE`. All descriptors may be explicitly deallocated, however the OCI will deallocate a descriptor if the environment handle is deallocated.

Related Functions

OCIDescriptorAlloc()

## OCIHandleAlloc()

Purpose

This call returns a pointer to an allocated and initialized handle.

Syntax

    sword OCIHandleAlloc ( CONST dvoid   *parenth,
                           dvoid         **hndlpp,
                           ub4           type,
                           size_t        xtramem_sz,
                           dvoid         **usrmempp );

Parameters

parenth (IN)

  An environment handle.

hndlpp (OUT)

  Returns a handle.

type (IN)

  Specifies the type of handle to be allocated. The allowed handles are described in this table:

  See Also: Table 2-1, "OCI Handle Types"

xtramem_sz (IN)

  Specifies an amount of user memory to be allocated.

usrmempp (OUT)

  Returns a pointer to the user memory of size `xtramem_sz` allocated by the call for the user.

Comments

Returns a pointer to an allocated and initialized handle, corresponding to the type specified in `type`. A non-`NULL` handle is returned on success. All handles are allocated with respect to an environment handle which is passed in as a parent handle.

No diagnostics are available on error. This call returns `OCI_SUCCESS` if successful, or `OCI_INVALID_HANDLE` if an error occurs.

Handles must be allocated using `OCIHandleAlloc()` before they can be passed into an OCI call.

To allocate and initialize an environment handle, call OCIEnvInit().

See Also: For more information about using the `xtramem_sz` parameter for user memory allocation, refer to "User Memory Allocation"

Related Functions

OCIHandleFree(), OCIEnvInit()

## OCIHandleFree()

Purpose

This call explicitly deallocates a handle.

Syntax

    sword OCIHandleFree ( dvoid     *hndlp,
                          ub4       type );

Parameters

hndlp (IN)

  A handle allocated by `OCIHandleAlloc()`.

type (IN)

  Specifies the type of storage to be freed. The handles are described in this table:

  See Also: Table 2-1, "OCI Handle Types"

Comments

This call frees up storage associated with a handle, corresponding to the type specified in the `type` parameter.

This call returns either `OCI_SUCCESS` or `OCI_INVALID_HANDLE`.

All handles may be explicitly deallocated. The OCI will deallocate a child handle if the parent is deallocated.

When a statement handle is freed, the cursor associated with the statement handle will be closed, but the actual cursor closing may be deferred to the next round trip to the server. So if the application needs to close the cursor immediately, you can make a server round trip call, such as `OCIServerVersion()` or `OCIPing()`, after the `OCIHandleFree()` call.

Related Functions

OCIHandleAlloc(), OCIEnvInit()

## OCIParamGet()

Purpose

Returns a descriptor of a parameter specified by position in the describe handle or statement handle.

Syntax

    sword OCIParamGet ( CONST dvoid       *hndlp,
                        ub4               htype,
                        OCIError          *errhp,
                        dvoid             **parmdpp,
                        ub4               pos );

Parameters

hndlp (IN)

  A statement handle or describe handle. The `OCIParamGet()` function will return a parameter descriptor for this handle.

htype (IN)

  The type of the handle passed in the `hndlp` parameter. Valid types are:

- `OCI_DTYPE_PARAM`, for a parameter descriptor

- `OCI_HTYPE_COMPLEXOBJECT`, for a complex object retrieval handle

- `OCI_HTYPE_STMT`, for a statement handle

errhp (IN/OUT)

  An error handle you can pass to `OCIErrorGet()` for diagnostic information in the event of an error.

parmdpp (OUT)

  A descriptor of the parameter at the position given in the `pos` parameter, of handle type `OCI_DTYPE_PARAM`.

pos (IN)

  Position number in the statement handle or describe handle. A parameter descriptor will be returned for this position.

  Note: `OCI_ERROR` is returned if there are no parameter descriptors for this position.

Comments

This call returns a descriptor of a parameter specified by position in the describe handle or statement handle. Parameter descriptors are always allocated internally by the OCI library. They can be freed using `OCIDescriptorFree()`. For example, if you fetch the same column metadata for every execution of a statement, then the program will leak memory unless you explicitly free the parameter descriptor between each call to `OCIParamGet()`.

See Also: Appendix A, "Handle and Descriptor Attributes", for more detailed information about parameter descriptor attributes.

Related Functions

OCIAttrGet(), OCIAttrSet(), OCIParamSet(), OCIDescriptorFree()

## OCIParamSet()

Purpose

Used to set a complex object retrieval (COR) descriptor into a COR handle.

Syntax

    sword OCIParamSet ( dvoid          *hndlp,
                        ub4            htype,
                        OCIError       *errhp,
                        CONST dvoid    *dscp,
                        ub4            dtyp,
                        ub4            pos );

Parameters

hndlp (IN/OUT)

  Handle pointer.

htype (IN)

  Handle type.

errhp (IN/OUT)

  An error handle you can pass to `OCIErrorGet()` for diagnostic information in the event of an error.

dscp (IN)

  Complex object retrieval descriptor pointer.

dtyp (IN)

  Descriptor type. The descriptor type for a COR descriptor is `OCI_DTYPE_COMPLEXOBJECTCOMP`.

pos (IN)

  Position number.

Comments

The COR handle must have been previously allocated using OCIHandleAlloc(), and the descriptor must have been previously allocated using OCIDescriptorAlloc(). Attributes of the descriptor are set using OCIAttrSet().

See Also: For more information about complex object retrieval, see "Complex Object Retrieval".

Related Functions

OCIParamGet()